If you don't read this document, please read at least the shortcuts and tips by choosing GifBuilder Shortcuts in the Help menu ('?' at the right of the menu bar).
The tutorial in the Tutorial folder is also a good way to learn step by step how to create basic animations and use them on the Web.
GifBuilder is a scriptable utility for creating animated GIF files. Its input is an existing animated GIF, a bunch of PICT, GIF, TIFF and/or Photoshop files, a QuickTime movie, a PICS file, an Adobe Premiere FilmStrip 1.0 file, or the layers of an RGB or grayscale Adobe Photoshop 3.0 file, and its output is a GIF89a file with multiple images.
Options include pixel depth, color palette, interlacing, transparency, interframe delay, disposal method, frame offset, looping and dithering.
GifBuilder should ultimately be placed onto many ftp archives, including Info-Mac (in gst/grf), Umich (in graphics/graphicsutil) and their mirrors.
Please read this document carefully if you want to get the best of GifBuilder. There are several shortcuts which can make your work much easier.
Basic Usage
1) Draw each frame
Use any drawing program able to save as PICT, GIF, TIFF or Photoshop 2.5/3.0. Save frames in a new folder to make their retrieval easier. If you name them in alphabetical order (e.g. 0001.tiff, 0002.tiff, etc.), you can easily sort them later.
2) Collect frames in GifBuilder
Launch GifBuilder, be sure that there aren't frames from a previous animation in the Frames window (if that's the case, choose New in the File menu), and drag the frames from the Finder into the Frames window. Supported files are PICT, GIF, TIFF (baseline) and Photoshop 2.5 or 3 (bitmap, grayscale (or duotone, which are read as grayscale), indexed or RGB). If you don't have the Drag Manager (standard since MacOS 7.5), you can add each frame by choosing Add Frame in the File menu. You can also copy a picture from another application, or drag it. Then, check that they're in the correct order and, if necessary, change their order by dragging frames. You can also remove the selected frame(s) by choosing Clear in the Edit menu or hitting Backspace, sort them and reverse their order. Double-clicking a frame will open it in its own application; if you modify it, save it and choose Reload Frames in the File menu to update your changes (the Save command always use the disk copy).
3) Set the options
Set the standard graphic options (pixel depth, color palette and dithering); the GIF options (size, interlacing, transparency); and the animation options (interframe delay, disposal method, frames position and looping). Some of these properties (transparency, interframe delay, disposal method and position) are attached to individual frames; select the frame or group of frames before changing them. If no frame is selected, the settings will apply to the default values used for images you import. See below for more details.
You can save the default options by choosing Save Options in the Options menu.
Tip: Most options displayed in the Frames window can be changed by clicking or double-clicking them.
4) Check the animation
Choose Run in the Animation menu. To display a specific frame, stop the animation and select it in the Frames window. You can also use the Home, End, Up and Down keys. To start from the first selected frame, choose Continue. In the Animation window, you can move a frame by dragging it (the frame will be drawn on an onion skin if you hold down the Option key), or select the transparent color by Shift-clicking it (you can do it even when the animation is running, but depending on the speed, you'd better stop it first!). To position precisely the selected frames, choose Frame Position in the Options menu, or use the arrow keys (hold down the Option key if the Frames window is active).
5) Build the animation
Choose Save As in the File menu. Alternatively, you can drag the Animated GIF icon from the animation window to any location in the Finder.
6) Add an image tag to your HTML page
Choose Copy HTML Image Tag in the Edit menu, and paste the resulting IMG tag in your HTML page. IMG fields contain a relative URL with the current name of the animation as well as the width and height. Of course, you can edit the tag to change the path of the image or add optional fields like ALT and ALIGN. Alternatively, you can drag the </> symbol from the animation window to your HTML editor if it accepts drag-and-drop.
Options
Interlaced: With interlacing, a first rough image is loaded first, and then the vertical resolution improves in three additional passes. It isn't very useful for animations.
Suggested setting: off
Colors and Depth: For cross-platform web animations, the 6x6x6 color table is recommended. The system (or grayscale) 1 bit/pixel table should be used for black and white images. Images created with other settings are likely to be dithered on color-table-based machines. Set the Remove Unused Colors option in the Colors submenu to let GifBuilder keep only the colors present in the animation; this may reduce the file size a bit.
Suggested setting: 6x6x6 Palette and Remove Unused Colors.
Dithering: Dithering is a way to simulate intermediate color shades with clouds of points. It should be used with continuous-tone images. With dithering, the color table should be chosen so that the image isn't dithered a second time on the target machine (see above), and transparency should be off.
Suggested setting: on for photographic images, off for drawings with few colors.
Image Size: When Minimum Size is on, the size is calculated so that the animation's bottom right corner corresponds to the rightest lowest frame. Frames are always cropped to fit in the animation bounding box.
Suggested setting: Minimum Size
Background Color: The Background Color is the color used to paint the animation bounding box where no frame is displayed. With some Web browsers, the page background is used instead.
Suggested setting: any
Loop: The Loop option specifies how many times the animation is repeated. Some browsers don't recognize this option, while others loop an unlimited number of times if the setting is more than 1.
Suggested setting: No or Forever
Transparent Background: All pixels wich have the color specified by the Transparent Background are left untouched when the frame is rendered.
Suggested setting: No or First Pixel
Frame Position: Each frame can be shifted by an arbitrary amount. The Frame Position specifies the horizontal and vertical distances between the top left animation corner and the top left frame corner. Positive values push the frame to the left and to the lower part. Negative values result in a cropped frame. Relative positions are relative with respect to their previous values. One can also specify velocities, i.e. offsets between each frame position.
Suggested setting: create whole frames at (0,0) and use Frame Optimization to do the work for you
Interframe Delay: The Interframe Delay is the delay between the current frame and the following frame renderings. It's specified in hundredths of seconds (i.e. 100 means 1 second).
Suggested setting: don't use As Fast As Possible, because it might be really to fast on fast machines.
Disposal Method: The Disposal Method specifies what each frame becomes once the interframe delay is elapsed. Use Unspecified when transparency is off and each frame covers the whole animation, Do Not Dispose when you want to add some bits of image to the previous animation state, Revert to Background for moving objects on a transparent background, and Revert to Previous for moving objects on a background you've drawn with an earlier large frame. Note that Revert to Background isn't supported by some browsers.
Suggested setting: Do Not Dispose for opaque animations, Revert to Background for transparent ones.
Frame Optimization: The Frame Optimization option crops each frame (but the first one) to the part that has changed. This can result in tremendous file size savings. If some, but not all, of the frames have the Disposal Method set to Revert to Background, you are warned that this may give unexpected results.
Suggested setting: on (unless you need compatibility with primitive GIF decoders; see "Compatibility with Other Programs" below)
Frame Expansion: The Frame Expansion option does the opposite of Frame Optimization, i.e. it saves only whole frames. You shouldn't have to use it, but it can help with some GIF decoders (like old versions of Internet Explorer) that don't interpret correctly the frame position.
Suggested setting: off (unless you need compatibility with primitive GIF decoders; see "Compatibility with Other Programs" below)
Remarks
New: After asking you if you want to save your previous animation, New removes all the frames and reads the default settings from the Preference file.
Open: You can open an existing animation, or append to the end of the current animation by holding down the Shift key and choosing Open in the File menu or typing Command-Shift-O.
Frames displayed in italic are loaded in memory, while those displayed in roman correspond to separate files.
Save Selection: only the selected frames are saved. Equivalent to Clear what is not selected, Save As, and Undo. Can be used to export single frames as GIF files.
Convert: You can convert a QuickTime movie, a PICS or a FilmStrip directly to an animated GIF without opening it, by choosing Convert in the File menu. This saves a lot of memory, but is less flexible: the current options are used, all the frames are saved, and no frame optimization is performed.
Clear: Clear (in the Edit menu) or the Backspace key deletes the selected frames. To preserve the timing, hold down the Shift key and choose Special Clear or type Backspace. Example:
Before Clear:╩
Clear:╩
Shift-Clear:╩
Undo: Undo allows to return to the state just before the last operation which changed the frames or frame order.
Color palette: System Palette and Gray Shades are fixed palette. Best Palette is optimized for all the frames simultaneously. 6x6x6 Palette is a subset of the System palette where each component takes the six values 0, 51, 102, 153, 204 and 255; it has 6x6x6 = 216 entries. It's the palette used by NetScape for Windows, so you might want to choose it to avoid additional dithering on both Macintosh and Windows machines. Load Palette allows to use a Photoshop-compatible palette file or the global palette of any GIF file. Three such palettes are included with GifBuilder: "Gray from 6x6x6 Palette" (six gray values of the 6x6x6 palette), "2x2x2 Palette" (eight basic colors where each component is 0 or 255), or "16 from 6x6x6 Palette", superset of the previous one with eight additional colors: (153,153,153), (0,153,255), (255,51,0), (51,153,0), (255,153,255), (153,204,255), (255,255,153) and (204,204,204) (see below). All of them should give good results on both the Mac and Windows.
╩
Note that the 4-bits-per-pixel System palette has some intermediate colors and shouldn't be used if you're concerned about cross-platform issues.
To reuse the color palette of an existing GIF, open the GIF file with Open (in the File menu) and save the palette with Save Palette (in the Colors submenu of the Options menu). The GIF file doesn't have to contain multiple frames.
The format of palette files is 256 entries of three bytes which represent the red, green and blue values of the corresponding index. 0 is black, and 255 is the maximum intensity. For palettes of less than 256 colors, fill the unused entries with the last used one. The file type is '8BCT', and the file creator should be 'gfBr' (GifBuilder's) to have a nice icon. Note that in AppleScript, RGB values are in the range 0-65535; to convert them from a byte value, multiply them by 257.
When you load a palette, you can't choose the depth anymore. Choose a System, grayscale or best palette before changing the depth.
You can examine the current palette by choosing Show Colors in the Window menu, and load one by dragging a palette file or a GIF file in the Colors window.
Drag and Drop: Drag and Drop is an easy way to move information from one program to another. GifBuilder supports this feature as a shortcut for several operations:
- You can drag frame files from the Finder or frame pictures from any program supporting it (e.g. the ScrapBook) into the Frames window.
- You can drag a palette file or a GIF file to the Colors window; in the case of a GIF file, its global color palette is used.
- You can drag the Animated GIF icon from the Animation window to any location in the Finder to create an animated GIF there.
- You can drag the </> icon from the Animation window to text editors and HTML editors that support Drag and Drop (e.g. SimpleText, BBEdit, and Adobe PageMill 2). An <img> HTML tag is inserted, like what you get with Copy HTML Image Tag.
Effects
Effects are commands whose purpose is to modify the animation to achieve some visual enhancement. They apply to the selected frames by modifying them (static filters) or inserting new frames (dynamic filters and transitions). Selected frames are expanded to the area of the animation. They are rendered using the current color palette. Consequently, to have the desired effect, check that the size and palette of the animation before making a transition. In some rare cases, depending on the disposal method, this may modify the animation in unexpected ways. You may also want to check the transparency and interframe delay, which is set to the default values. Since only the new frames are selected, you can change these settings very easily.
Static Filters
You can apply one of the static filters of the Effect menu to the selected frames.
Dynamic Filters
You can apply one of the dynamic filters of the Effect menu to the selected frames. A dynamic filter is a filter that adds frames with a more and more dramatic effect. You can put them either before the existing frames to reveal them, or after them to hide them. The number of new frames which are inserted before the first selected frame is one less than the number of steps.
Transitions
To create a transition between two frames, select the second frame and choose one of the transitions in the Effects menu. The number of new frames which are inserted before the first selected frame is one less than the number of steps. The transition frames have the size of the animation. To create a transition from or to a plain color, use Add Color Matte (also in the Effects menu) to insert a plain frame first.
Scripting
Warning: scripting support is experimental. Some functionality is missing. This should be fixed in future releases.
The core AppleEvents and a rudimentary object model are partially implemented, allowing to create new and modify existing animations. Here is an example of what can be done:
tell application "GifBuilder"
open file "animation.gif" -- opens an existing animation
make new frame at the beginning ┬
with data {contents:somePictObject} -- prepends a new frame with default frame options
make new frame at the end ┬
with data {contents:file "lastFrame.tiff",
translation:{10, 10},
transparency:first pixel,
disposal method:restore to background,
interframe delay:50} -- appends another frame, with specified options
make new frame before 5th frame with data {contents:file "newFrame.pict"}
-- inserts a frame
save in file "animation2.gif" -- saves the animation in a new file
end tell
The color values are in the range 0 (black) - 65535 (maximum intensity). The PICTs can be created by any good graphic (and many other) applications.
And here is a "real" example that creates a bouncing ball on a transparent black background with clip2gif:
property w : 10
property h : 95
tell application "GifBuilder"
new
repeat with t from -13 to 12
set y to t * t / 2
tell application "clip2gif-ppc" to set p to save {w, h} in picture
drawing {{rectangle:{0, 0, w, h}}, {disk:{0, y, w, y + w}, color:{65535, 0, 0}}}
make new frame at end
with data {contents:p, transparency:first pixel, disposal method:restore to background}
end repeat
set loop to 0
save in new file
run animation
end tell
Results
Some option combinations can give unexpected results; this may be caused by strange features, viewer bugs, or GifBuilder bugs. If you don't succeed in creating files that load correctly in NetScape, choose Reset to Factory Settings in the Options menu and import your frames again.
One of the main goals of GifBuilder is to stick as closely as possible to the GIF 89a specifications, not to reproduce the way animations are performed on some particular browser.
Requirements
GifBuilder requires System 7 or above and 32-bit Color Quickdraw. The Drag Manager (which comes with PowerTalk and System 7.5) is recommended. AppleScript (as well as ObjectSupportLib on PowerMacs) is obviously needed to Apple-script GifBuilder. QuickTime is needed for importing QuickTime movie. If Convert (in the File menu) is dimmed, QuickTime is not correctly installed.
The animation, as well as the individual frames if they're loaded, must fit in RAM; set the application memory partition appropriately (Get Info in the Finder). GifBuilder shouldn't crash in low memory conditions; but if it does, try to increase the memory partition to some high value (if you can) before sending me a bug report.
Frequently Asked Questions
About Animated GIF
Local animations are ok, but when I use an HTTP server, they don't loop and the end of the last frame is corrupted. What happens?
You probably corrupted the file when you uploaded it to the server. Be sure that you choose the binary (or raw) mode (not MacBinary) for your file transfer.
Can I choose which frame is displayed by old browsers?
No. Some GIF decoders display only the first frame, while others render all the images but don't recognize the looping NetScape 2.0 extension.
Netscape doesn't display correctly transparent animations. Is there a trick?
Try to set the Disposal Method of all the frames to Revert to Background, and specify a background GIF to be tiled behind the HTML page with the <body> tag: <body background=tile.gif>.
There is a flash when the animation loops. What can I do?
Try to remove interlacing and to use a cross-platform color palette (e.g. the 6x6x6 Palette).
Is it possible to have an animated background?
Not with the current versions of Netscape (2.0(x)).
Should I put the original images on my server?
No. Animated GIFs are completely self-contained. They don't contain any references to the original files.
How can I stop animations in NetScape 2.0 for the Mac?
You should hold down the Command key and hit the dot key exactly when NetScape reloads the image from its cache.
Why can't I {go back and forth | repeat only some frames}?
Because these features wouldln't be supported by any other browser. Animations created by GifBuilder have to stick with the GIF specifications.
About GifBuilder
I want to keep the color palette of my frames, which are GIF files. What should I do?
Open one of your frames in GifBuilder with Open, add the other frames and set their options, and save the result.
Why can't I choose a System Palette with a depth of 3, 5, 6 or 7 bits/pixel, or a 6x6x6 Palette with a depth smaller than 8?
Because there is no such palettes.
Why is the transparency set to First Pixel even if I specify a color?
In GIF files, the transparency is always based on a color. When GifBuilder reads an animation, it looks at the first pixel to see if it's the transparent color, and if so reports that the transparency is based on it.
Why do I get the error "File not found" when I save the animation?
For disk-based frames (whose name is displayed in roman), GifBuilder uses the content of the files when it builds the animation or when you choose Reload Frames in the File menu. You should leave the files where they were when you imported them.
Why do I get an error message saying that a feature isn't supported when I import a TIFF or Photoshop image?
Because GifBuilder supports only the most common, publicly documented and patent-free formats. Supported TIFF files include bitmap, grayscale, indexed and RGB, uncompressed or compressed with Packbits. Supported Photoshop files include bitmap, grayscale, indexed, RGB and duotone (read as grayscale), version 2.5 or 3.0.
How can I choose the comment displayed by JPEGView and other utilities?
You can't. GifBuilder adds a fixed comment containing its and my names. This is deliberate.
I've found a GifBuilder bug! Revert to Previous doesn't work!
If your browser doesn't handle correctly a feature, this isn't necessarily a GifBuilder bug. This one, for instance, is most probably not.
Images are dithered even if I don't select it in GifBuilder! Why?
Images are usually dithered by the browser if its palette isn't the same as the GIF's. You'd better use the 6x6x6 palette provided with GifBuilder, which is used by several browsers on the Mac as well as on alien machines, and let GifBuilder do the dithering if you need to.
The blur filter posterizes the frames. Why?
Filters and transitions render the frames using the current color palette, then create new intermediate frames with 24 bits/pixel. The result is displayed in the Preview window and saved as GIF using the current palette again. Usual palettes have only a limited number of shades, and that's especially visible with blurred images. You can use the Best Palette or Gray Shades, or set dithering on, to avoid posterizing.
The peal transition doesn't use the color I choose for the back of the sheet. Why?
The color you choosed must not be in the current color palette (see question above). Use a darker color or a less transparent alpha value (larger).
I don't use Windows 3.1 anymore. Are you working on a Windows NT version?
GifBuilder runs on the Mac. I don't intend to port it to any currently available operating system (I might have ideas about new ones, however).
So give me the source, I'll port it.
First, I don't make the source code available. Second, even if it was, the GIF part is a very small part of the whole program. The remaining is closely tied to the Mac user interface and graphical model.
Compatibility with Other Programs
Programs are mentionned here for information only. Some of them are quite good (imo), others aren't (imho); don't try to deduce which ones I like or love.
Netscape Navigator 2.01 for Mac
Netscape Navigator 2.01 for Mac doesn't support all the GIF89a features. Features not supported include Revert to Previous, all the transparency specifications except the one for the first frame (which is applied globally to all the frames), transparency without a background GIF in the <body> tag (use <body background=tile.gif>), and the number of loops.
Microsoft Internet Explorer 2.1 for Mac
Much better support than in previous versions. The number of loops is taken into account.
NCSA Mosaic 2.0.1 for Mac
Only the last frame is displayed. Partial frames result in corrupted images (version 3.0A2 has the same problems); use Expand Frames.
Apple Cyberdog 1.0
Neither the looping nor the timing info is taken into account. At the end, the last frame is displayed.
Adobe Photoshop 3.0
You can create individual frames in Photoshop and save them as Photoshop bitmap, grayscale or RGB files, and drag them from the Finder to the GifBuilder Frames window (duotone files can also be imported, but color information is lost). PICT, GIF and TIFF files are of course also possible.
GifBuilder can also load the layers of a grayscale or RGB Photoshop 3.0 file. Each layer is rendered onto a white opaque background. To create the animation, you can draw the first frame on the Background layer. Then for each new frame, choose Duplicate Layer, hide the other layers, and edit the new one.
Adobe Premiere 4.0
You can save animations as QuickTime movies, FilmStrips or bunches of numbered PICT files. The FilmStrip format is recommended, because it's more convenient that several PICT files and guarranties that no lossy compression method is used. You can also edit it in Photoshop.
Adobe PageMill 2.0
You can drag the </> icon from the Animation Window to a PageMill window to insert a tag. You should save the animated GIF in the same folder as the HTML document, or edit the URL.
Specular Infini-D 3.0 and LogoMotion 2.0
You can save animations either as QuickTime movies or PICS, and open them in GifBuilder to save them as animated GIF. The PICS format is recommended, because it guarranties that no lossy compression method is used.
Other animated GIF utilities
You can load animated GIF files created with other utilities to study and change the settings.
Small Print
This document is Copyright 1995-1997, Yves Piguet. All rights reserved.
The author makes no warranty with respect to this document, its quality, accuracy, or fitness for a particular purpose. As a result, this document is provided "as is", and the user is assuming the entire risk as to its quality and accuracy.
Marks mentionned here are for information only; most of them are trade marks or registered trade marks.
